using System.Text.Json.Serialization;

namespace Sage.CloudStorage.Qiniu.Models
{
    /// <summary>
    /// 初始化分片上传响应类
    /// 包含七牛云分片上传初始化后返回的关键信息
    /// </summary>
    /// <remarks>
    /// **分片上传流程**：
    /// 1. **初始化**：调用初始化API，获取UploadId（本响应）
    /// 2. **上传分片**：使用UploadId上传各个分片
    /// 3. **完成上传**：提交所有分片信息，完成文件合并
    /// 
    /// **响应用途**：
    /// - 提供后续分片上传操作的唯一标识
    /// - 告知客户端上传任务的有效期限
    /// - 用于断点续传功能的状态管理
    /// 
    /// **时效性说明**：
    /// - UploadId有固定的7天有效期
    /// - 过期后无法继续使用，需要重新初始化
    /// - 建议在有效期内完成所有分片上传
    /// </remarks>
    public class InitiateMultipartUploadResponse
    {
        /// <summary>
        /// 初始化文件生成的唯一标识ID
        /// 用于后续所有分片上传操作的身份标识
        /// </summary>
        /// <remarks>
        /// **UploadId特性**：
        /// - 全局唯一标识符，由七牛云生成
        /// - 长度通常为24个字符的字符串
        /// - 在分片上传的整个生命周期中保持不变
        /// - 用于关联所有属于同一文件的分片
        /// 
        /// **使用场景**：
        /// - 上传单个分片时的必需参数
        /// - 列举已上传分片时的查询条件
        /// - 完成分片上传时的任务标识
        /// - 终止分片上传时的清理标识
        /// - 断点续传时的任务恢复标识
        /// 
        /// **存储建议**：
        /// - 建议在客户端持久化存储（如数据库、文件）
        /// - 用于实现断点续传功能
        /// - 在上传失败时用于清理资源
        /// - 可用于上传进度的跟踪和管理
        /// 
        /// **格式示例**：
        /// "5df9ea14834c512b2270234e"
        /// </remarks>
        [JsonPropertyName("uploadId")]
        public string UploadId { get; set; } = "";

        /// <summary>
        /// UploadId的过期时间（Unix时间戳，单位为秒）
        /// 表示此上传任务的绝对过期时间
        /// </summary>
        /// <remarks>
        /// **过期机制**：
        /// - 固定7天有效期，从初始化时间开始计算
        /// - 过期后UploadId自动失效，无法继续使用
        /// - 七牛云会自动清理过期任务的已上传分片数据
        /// - 过期时间不可延长，需要重新初始化
        /// 
        /// **时间计算**：
        /// - Unix时间戳格式（秒级精度）
        /// - 可以转换为本地时间进行显示
        /// - 建议在过期前预留足够的缓冲时间
        /// 
        /// **监控建议**：
        /// - 实时监控剩余有效时间
        /// - 在接近过期时提醒用户或自动处理
        /// - 记录过期情况用于优化上传策略
        /// 
        /// **时间转换示例**：
        /// ```csharp
        /// // 转换为本地时间
        /// var expireTime = DateTimeOffset.FromUnixTimeSeconds(response.ExpireAt);
        /// 
        /// // 计算剩余时间
        /// var remainingTime = expireTime - DateTimeOffset.UtcNow;
        /// 
        /// // 检查是否即将过期（如24小时内）
        /// var isExpiringSoon = remainingTime.TotalHours &lt; 24;
        /// ```
        /// 
        /// **注意事项**：
        /// - 客户端应该检查过期时间，避免使用过期的UploadId
        /// - 长时间上传的大文件需要考虑过期风险
        /// - 建议在上传前验证UploadId的有效性
        /// - 过期后重新初始化会产生新的UploadId
        /// </remarks>
        [JsonPropertyName("expireAt")]
        public long ExpireAt { get; set; }
    }
}
